home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / basic / ace24dist.lha / ace24.lha / include / utility / hooks.h < prev    next >
C/C++ Source or Header  |  1996-09-10  |  3KB  |  116 lines
  1. #ifndef UTILITY_HOOKS_H
  2. #define UTILITY_HOOKS_H 1
  3. /*
  4. ** hooks.h for ACE Basic
  5. **
  6. ** Note: Translated to ACE by ConvertC2ACE
  7. **       @ MapMeadow Software, Nils Sjoholm
  8. **
  9. **
  10. ** Date: 09/03/95
  11. **
  12. **
  13. */
  14.  
  15. /*
  16. ** This are the StructPointer defines for hooks.h
  17. */
  18. #ifndef HookPtr
  19. #define HookPtr ADDRESS
  20. #endif
  21. /*
  22. ** End of StructPointer defines for hooks.h
  23. */
  24.  
  25.  
  26. /*****************************************************************************/
  27.  
  28.  
  29. #ifndef EXEC_TYPES_H
  30. #include <exec/types.h>
  31. #endif
  32.  
  33. #ifndef EXEC_NODES_H
  34. #include <exec/nodes.h>
  35. #endif
  36.  
  37.  
  38. /*****************************************************************************/
  39.  
  40.  
  41. STRUCT Hook
  42.  
  43.     MinNode h_MinNode 
  44.     ADDRESS   h_Entry     /* assembler entry point */
  45.     ADDRESS   h_SubEntry  /* often HLL entry point */
  46.     ADDRESS       h_Data       /* owner specific    */
  47. END STRUCT 
  48.  
  49. /* Useful definition for casting function pointers:
  50.  * hook.h_SubEntry = (HOOKFUNC)AFunction
  51.  */
  52. /*
  53. typedef unsigned LONGINT *HOOKFUNC 
  54. */
  55.  
  56. /* Hook calling conventions.
  57.  *
  58.  * The function pointed to by Hook.h_Entry is called with the following
  59.  * parameters:
  60.  *
  61.  *  A0 - pointer to hook data structure itself
  62.  *  A1 - pointer to parameter structure ("message")
  63.  *  A2 - Hook specific address data ("object")
  64.  *
  65.  * Control will be passed to the routine h_Entry.  For many
  66.  * High-Level Languages (HLL),  this will be an assembly language
  67.  * stub which pushes registers on the stack,  does other setup, 
  68.  * and then calls the function at h_SubEntry.
  69.  *
  70.  * The standard C receiving code is:
  71.  *
  72.  *    HookFunc(STRUCT Hook *hook,  ADDRESS object,  ADDRESS message)
  73.  *
  74.  * Note that register natural order differs from this convention for C
  75.  * parameter order,  which is A0, A2, A1.
  76.  *
  77.  * The assembly language stub for "vanilla" C parameter conventions
  78.  * could be:
  79.  *
  80.  * _hookEntry:
  81.  *  move.l  a1, -(sp)          push message packet pointer
  82.  *  move.l  a2, -(sp)          push object pointer
  83.  *  move.l  a0, -(sp)          push hook pointer
  84.  *  move.l  h_SubEntry(a0), a0     fetch C entry point ...
  85.  *  jsr (a0)              ... and call it
  86.  *  lea 12(sp), sp         fix stack
  87.  *  rts
  88.  *
  89.  * With this function as your interface stub,  you can write a Hook setup
  90.  * function as:
  91.  *
  92.  * InitHook(STRUCT Hook *hook,  LONGINT (*c_function)(),  ADDRESS userdata)
  93.  *  
  94.  * LONGINT *hookEntry
  95.  *
  96.  *     hook->h_Entry    = hookEntry 
  97.  *     hook->h_SubEntry = c_function 
  98.  *     hook->h_Data = userdata 
  99.  * END STRUCT
  100.  *
  101.  * With a compiler capable of registerized parameters,  such as SAS C,  you
  102.  * can put the C function in the h_Entry field directly. For example,  for
  103.  * SAS C:
  104.  *
  105.  *   LONGINT __saveds __asm HookFunc(register __a0 STRUCT Hook *hook, 
  106.  *                 register __a2 ADDRESS         object, 
  107.  *                 register __a1 ADDRESS         message) 
  108.  *
  109.  */
  110.  
  111.  
  112. /*****************************************************************************/
  113.  
  114.  
  115. #endif /* UTILITY_HOOKS_H */
  116.